home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / clang / regexp3.zip / REGEXP.MAN < prev    next >
Text File  |  1994-01-21  |  10KB  |  205 lines
  1. " Copyright 1991 The Regents of the University of California.
  2. " All rights reserved.
  3. "
  4. " Redistribution and use in source and binary forms, with or without
  5. " modification, are permitted provided that the following conditions
  6. " are met:
  7. " 1. Redistributions of source code must retain the above copyright
  8. "    notice, this list of conditions and the following disclaimer.
  9. " 2. Redistributions in binary form must reproduce the above copyright
  10. "    notice, this list of conditions and the following disclaimer in the
  11. "    documentation and/or other materials provided with the distribution.
  12. " 3. All advertising materials mentioning features or use of this software
  13. "    must display the following acknowledgement:
  14. "       This product includes software developed by the University of
  15. "       California, Berkeley and its contributors.
  16. " 4. Neither the name of the University nor the names of its contributors
  17. "    may be used to endorse or promote products derived from this software
  18. "    without specific prior written permission.
  19. "
  20. " THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. " ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. " IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. " ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. " FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. " DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. " OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. " HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. " LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. " OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. " SUCH DAMAGE.
  31. "
  32. "     @(#)regexp.3      5.2 (Berkeley) 4/20/91
  33. "
  34. April 20, 1991                       REGEXP 3
  35.  
  36. NAME
  37.  
  38.         regcomp ,
  39.         regexec ,
  40.         regsub ,
  41.         regerror
  42.  
  43.         regular expression handlers
  44.  
  45. SYNOPSIS
  46.  
  47.         #include <regexp.h>
  48.         regexp *regcomp "const char *exp"
  49.         int regexec "const regexp *prog" "const char *string"
  50.         void regsub "const regexp *prog" "const char *source" "char *dest"
  51.  
  52. DESCRIPTION
  53.  
  54.         The regcomp , regexec , regsub , and regerror functions
  55.         implement egrep 1-style regular expressions and supporting
  56.         facilities.
  57.  
  58.         The regcomp function compiles a regular expression into a
  59.         structure of type regexp , and returns a pointer to it. The
  60.         space has been allocated using malloc 3 and may be released by
  61.         free .
  62.  
  63.         The regexec function matches a NUL-terminated string against the
  64.         compiled regular expression in prog . It returns 1 for success
  65.         and 0 for failure, and adjusts the contents of prog's startp and
  66.         endp (see below) accordingly.
  67.  
  68.         The members of a regexp structure include at least the following
  69.         (not necessarily in order):
  70.  
  71.         char *startp[NSUBEXP];
  72.         char *endp[NSUBEXP];
  73.  
  74.         where NSUBEXP is defined (as 10) in the header file. Once a
  75.         successful regexec has been done using the regexp , each startp-endp
  76.         pair describes one substring within the string , with the startp
  77.         pointing to the first character of the substring and the endp
  78.         pointing to the first character following the substring. The 0th
  79.         substring is the substring of string that matched the whole
  80.         regular expression. The others are those substrings that matched
  81.         parenthesized expressions within the regular expression, with
  82.         parenthesized expressions numbered in left-to-right order of
  83.         their opening parentheses.
  84.  
  85.         The regsub function copies source to dest , making substitutions
  86.         according to the most recent regexec performed using prog . Each
  87.         instance of `&' in source is replaced by the substring indicated
  88.         by startp and endp . Each instance of \n , where n is a digit,
  89.         is replaced by the substring indicated by startp n and endp  n .
  90.         To get a literal `&' or \n into dest , prefix it with `\'; to
  91.         get a literal `\' preceding `&' or \n , prefix it with another
  92.         `\'.
  93.  
  94.         The regerror function is called whenever an error is detected in
  95.         regcomp , regexec , or regsub . The default regerror writes the
  96.         string msg , with a suitable indicator of origin, on the
  97.         standard error output and invokes exit 2 . The regerror function
  98.         can be replaced by the user if other actions are desirable.
  99.  
  100. REGULAR EXPRESSION SYNTAX
  101.  
  102.         A regular expression is zero or more branches , separated by
  103.         `|'. It matches anything that matches one of the branches.
  104.  
  105.         A branch is zero or more pieces , concatenated. It matches a
  106.         match for the first, followed by a match for the second, etc.
  107.  
  108.         A piece is an atom possibly followed by `*', `+', or `?'. An
  109.         atom followed by `*' matches a sequence of 0 or more matches of
  110.         the atom. An atom followed by `+' matches a sequence of 1 or
  111.         more matches of the atom. An atom followed by `?' matches a
  112.         match of the atom, or the null string.
  113.  
  114.         An atom is a regular expression in parentheses (matching a match
  115.         for the regular expression), a range (see below), `.' (matching
  116.         any single character), `^' (matching the null string at the
  117.         beginning of the input string), `$' (matching the null string at
  118.         the end of the input string), a `\' followed by a single
  119.         character (matching that character), or a single character with
  120.         no other significance (matching that character).
  121.  
  122.         A range is a sequence of characters enclosed in `[]'. It
  123.         normally matches any single character from the sequence. If the
  124.         sequence begins with `^', it matches any single character not
  125.         from the rest of the sequence. If two characters in the sequence
  126.         are separated by `-', this is shorthand for the full list of
  127.         ASCII characters between them (e.g. `[0-9]' matches any decimal
  128.         digit). To include a literal `]' in the sequence, make it the
  129.         first character (following a possible `^'). To include a literal
  130.         `-', make it the first or last character.
  131.  
  132. AMBIGUITY
  133.  
  134.         If a regular expression could match two different parts of the
  135.         input string, it will match the one which begins earliest. If
  136.         both begin in the same place but match different lengths, or
  137.         match the same length in different ways, life gets messier, as
  138.         follows.
  139.  
  140.         In general, the possibilities in a list of branches are
  141.         considered in left-to-right order, the possibilities for `*',
  142.         `+', and `?' are considered longest-first, nested constructs are
  143.         considered from the outermost in, and concatenated constructs
  144.         are considered leftmost-first. The match that will be chosen is
  145.         the one that uses the earliest possibility in the first choice
  146.         that has to be made. If there is more than one choice, the next
  147.         will be made in the same manner (earliest possibility) subject
  148.         to the decision on the first choice. And so forth.
  149.  
  150.         For example, (ab|a)b*c could match `abc' in one of two ways. The
  151.         first choice is between `ab' and `a'; since `ab' is earlier, and
  152.         does lead to a successful overall match, it is chosen. Since the
  153.         `b' is already spoken for, the `b*' must match its last
  154.         possibility -- the empty string -- since it must respect the
  155.         earlier choice.
  156.  
  157.         In the particular case where no `|'s are present and there is
  158.         only one `*', `+', or `?', the net effect is that the longest
  159.         possible match will be chosen. So  ab* , presented with
  160.         `xabbbby', will match `abbbb'. Note that if ab* , is tried
  161.         against `xabyabbbz', it will match `ab' just after `x', due to
  162.         the begins-earliest rule. (In effect, the decision on where to
  163.         start the match is the first choice to be made, hence subsequent
  164.         choices must respect it even if this leads them to less-
  165.         preferred alternatives.)
  166.  
  167. RETURN VALUES
  168.  
  169.         The regcomp function returns NULL for a failure (regerror
  170.         permitting), where failures are syntax errors, exceeding
  171.         implementation limits, or applying `+' or `*' to a possibly-null
  172.         operand.
  173.  
  174. SEE ALSO
  175.  
  176.         ed 1 ,
  177.         ex 1 ,
  178.         expr 1 ,
  179.         egrep 1 ,
  180.         fgrep 1 ,
  181.         grep 1 ,
  182.         regex 3
  183.  
  184. HISTORY
  185.  
  186.         Both code and manual page for regcomp , regexec , regsub , and
  187.         regerror were written at the University of Toronto and appeared
  188.         in 4.3 tahoe . They are intended to be compatible with the Bell
  189.         V8 regexp 3 , but are not derived from Bell code.
  190.  
  191. BUGS
  192.  
  193.         Empty branches and empty regular expressions are not portable to
  194.         V8.
  195.  
  196.         The restriction against applying `*' or `+' to a possibly-null
  197.         operand is an artifact of the simplistic implementation.
  198.  
  199.         Does not support egrep's newline-separated branches; neither
  200.         does the V8 regexp 3 , though.
  201.  
  202.         Due to emphasis on compactness and simplicity, it's not
  203.         strikingly fast. It does give special attention to handling
  204.         simple cases quickly.
  205.